@opentelemetry/node

OpenTelemetry Node SDK

This module provides automated instrumentation and tracing for Node.js applications.

For manual instrumentation see the @opentelemetry/tracing package.

How auto instrumentation works

This package exposes a NodeTracerProvider that will automatically hook into the module loader of Node.js.

For this to work, please make sure that NodeTracerProvider is initialized before any other module of your application, (like http or express) is loaded.

OpenTelemetry comes with a growing number of instrumentation plugins for well know modules (see supported modules) and an API to create custom plugins (see the plugin developer guide).

Whenever a module is loaded NodeTracerProvider will check if a matching instrumentation plugin has been installed.

Please note: This module does not bundle any plugins. They need to be installed separately.

If the respective plugin was found, it will be used to patch the original module to add instrumentation code. This is done by wrapping all tracing-relevant functions.

This instrumentation code will automatically

• extract a trace-context identifier from inbound requests to allow distributed tracing (if applicable)
• make sure that this current trace-context is propagated while the transaction traverses an application (see @opentelemetry/context-base for an in-depth explanation)
• add this trace-context identifier to outbound requests to allow continuing the distributed trace on the next hop (if applicable)
• create and end spans

In short, this means that this module will use provided plugins to automatically instrument your application to produce spans and provide end-to-end tracing by just adding a few lines of code.

Creating custom spans on top of auto-instrumentation

Additionally to automated instrumentation, NodeTracerProvider exposes the same API as @opentelemetry/tracing, allowing creating custom spans if needed.

Installation

npm install --save @opentelemetry/api
npm install --save @opentelemetry/node

# Install instrumentation plugins
npm install --save @opentelemetry/plugin-http
npm install --save @opentelemetry/plugin-https

Usage

The following code will configure the NodeTracerProvider to instrument http (and any other installed supported modules) using @opentelemetry/plugin-http.

const { NodeTracerProvider } = require('@opentelemetry/node');

// Create and configure NodeTracerProvider
const provider = new NodeTracerProvider();

// Initialize the provider
provider.register()

// Your application code - http will automatically be instrumented if
// @opentelemetry/plugin-http is present
const http = require('http');

Plugin configuration

User supplied plugin configuration is merged with the default plugin configuration. Furthermore, custom plugins that are configured are implicitly enabled just as default plugins are.

In the following example:

• the default express plugin is disabled
• the http plugin has a custom config for a requestHook
• the customPlugin is loaded from the user supplied path
• all default plugins are still loaded if installed.

const provider = new NodeTracerProvider({
  plugins: {
    express: {
      enabled: false,
    },
    http: {
      requestHook: (span, request) => {
        span.setAttribute("custom request hook attribute", "request");
      },
    },
    customPlugin: {
      path: "/path/to/custom/module",
    },
  },
});

Disable Plugins with Environment Variables

Plugins can be disabled without modifying and redeploying code. OTEL_NO_PATCH_MODULES accepts a comma separated list of module names to disabled specific plugins. The names should match what you use to require the module into your application. For example, OTEL_NO_PATCH_MODULES=pg,https will disable the postgres plugin and the https plugin. To disable all plugins, set the environment variable to *.

Examples

See how to automatically instrument http and gRPC / grpc-js using node-sdk.

Useful links

• For more information on OpenTelemetry, visit: https://opentelemetry.io/
• For more about OpenTelemetry JavaScript: https://github.com/open-telemetry/opentelemetry-js
• For help or feedback on this project, join us in GitHub Discussions

License

Apache 2.0 - See LICENSE for more information.

Changelog

0.16.0

:boom: Breaking Change

• opentelemetry-exporter-collector
  • #1863 fix(exporter-collector): all http export requests should share same a… (@blumamir)
• opentelemetry-api, opentelemetry-exporter-collector, opentelemetry-exporter-jaeger
  • #1860 chore: fixing status code aligning it with proto (@obecny)

:rocket: (Enhancement)

• opentelemetry-core
  • #1837 chore(http-propagation): reduce complexity of traceparent parsing (@marcbachmann)
• opentelemetry-api, opentelemetry-exporter-collector, opentelemetry-exporter-jaeger
  • #1860 chore: fixing status code aligning it with proto (@obecny)

:bug: (Bug Fix)

• opentelemetry-exporter-collector
  • #1863 fix(exporter-collector): all http export requests should share same a… (@blumamir)

:books: (Refine Doc)

• opentelemetry-api
  • #1864 chore: export API singleton types (@dyladan)
• opentelemetry-api-metrics, opentelemetry-api, opentelemetry-context-async-hooks, opentelemetry-context-base, opentelemetry-context-zone-peer-dep, opentelemetry-context-zone, opentelemetry-core, opentelemetry-exporter-collector-grpc, opentelemetry-exporter-collector-proto, opentelemetry-exporter-collector, opentelemetry-exporter-jaeger, opentelemetry-exporter-prometheus, opentelemetry-exporter-zipkin, opentelemetry-grpc-utils, opentelemetry-instrumentation-fetch, opentelemetry-instrumentation-grpc, opentelemetry-instrumentation-http, opentelemetry-instrumentation-xml-http-request, opentelemetry-instrumentation, opentelemetry-metrics, opentelemetry-node, opentelemetry-plugin-grpc-js, opentelemetry-plugin-grpc, opentelemetry-plugin-http, opentelemetry-plugin-https, opentelemetry-propagator-b3, opentelemetry-resource-detector-aws, opentelemetry-resource-detector-gcp, opentelemetry-resources, opentelemetry-sdk-node, opentelemetry-semantic-conventions, opentelemetry-shim-opentracing, opentelemetry-tracing, opentelemetry-web
  • #1866 chore: remove all gitter links and replace with dicussions (@dyladan)
• opentelemetry-exporter-jaeger
  • #1869 Add info that the project only works with Node.js (@JapuDCret)
• opentelemetry-api-metrics, opentelemetry-api, opentelemetry-context-async-hooks, opentelemetry-context-base, opentelemetry-context-zone-peer-dep, opentelemetry-context-zone, opentelemetry-core, opentelemetry-exporter-collector-grpc, opentelemetry-exporter-collector-proto, opentelemetry-exporter-collector, opentelemetry-exporter-jaeger, opentelemetry-exporter-prometheus, opentelemetry-exporter-zipkin, opentelemetry-grpc-utils, opentelemetry-instrumentation-fetch, opentelemetry-instrumentation-grpc, opentelemetry-instrumentation-http, opentelemetry-instrumentation-xml-http-request, opentelemetry-instrumentation, opentelemetry-metrics, opentelemetry-node, opentelemetry-plugin-grpc-js, opentelemetry-plugin-grpc, opentelemetry-plugin-http, opentelemetry-plugin-https, opentelemetry-resource-detector-aws, opentelemetry-resource-detector-gcp, opentelemetry-resources, opentelemetry-sdk-node, opentelemetry-semantic-conventions, opentelemetry-shim-opentracing, opentelemetry-tracing, opentelemetry-web
  • #1865 Fix all links to point to main (@dyladan)
• Other
  • #1858 docs: update contribution documentation (@drexler)

Committers: 6

• Amir Blum (@blumamir)
• Bartlomiej Obecny (@obecny)
• Daniel Dyla (@dyladan)
• Marc Bachmann (@marcbachmann)
• @JapuDCret
• andrew quartey (@drexler)